---
sidebar_position: 4
description: Map enums
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Enum mappings

An enum mapping can be customized by setting the strategy to use.
Apply the `MapEnumAttribute` and pass the strategy to be used for this enum.
It is also possible to set the strategy for the entire mapper via the `MapperAttribute`.
Available strategies:

| Name                | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| ByValue             | Matches enum entries by their values (default)                              |
| ByValueCheckDefined | Matches enum entries by their values, checks if the target value is defined |
| ByName              | Matches enum entries by their exact names                                   |

The `IgnoreCase` property allows to opt in for case insensitive mappings (defaults to `false`).

<Tabs>
  <TabItem value="global" label="Global (mapper level)" default>
  
  Applied to all enums mapped inside this mapper.
  
  ```csharp
  // highlight-start
  [Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName, EnumMappingIgnoreCase = true)]
  // highlight-end
  public partial class CarMapper
  {
      ...
  }
  ```
  
  </TabItem>
  <TabItem value="enum" label="Enum (mapping method level)">
  
  Applied to the specific enum mapped by this method.
  Attribute is only valid on mapping method with enums as parameters.
  
  ```csharp
  [Mapper]
  public partial class CarMapper
  {
      // highlight-start
      [MapEnum(EnumMappingStrategy.ByName, IgnoreCase = true)]
      // highlight-end
      public partial CarMakeDto MapMake(CarMake make);
  }
  ```
  
  </TabItem>
</Tabs>

## Enum from/to string naming strategies

Enum from/to strings mappings can be customized by setting the enum naming strategy to be used.
You can specify the naming strategy using `NamingStrategy` in `MapEnumAttribute` or `EnumNamingStrategy` in `MapperAttribute` and `MapperDefaultsAttribute`.
Available naming strategies:

| Name                               | Description                                                                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MemberName                         | Matches enum values using their name. (default)                                                                                                                                             |
| CamelCase                          | Matches enum values using camelCase.                                                                                                                                                        |
| PascalCase                         | Matches enum values using PascalCase.                                                                                                                                                       |
| SnakeCase                          | Matches enum values using snake_case.                                                                                                                                                       |
| UpperSnakeCase                     | Matches enum values using UPPER_SNAKE_CASE.                                                                                                                                                 |
| KebabCase                          | Matches enum values using kebab-case.                                                                                                                                                       |
| UpperKebabCase                     | Matches enum values using UPPER-KEBAB-CASE.                                                                                                                                                 |
| ComponentModelDescriptionAttribute | Matches enum values using the `Description` property of the `System.ComponentModel.DescriptionAttribute`. If the attribute is not present or the property is null, the member name is used. |
| SerializationEnumMemberAttribute   | Matches enum values using the `Value` property of the `System.Runtime.Serialization.EnumMemberAttribute`. If the attribute is not present or the property is null, the member name is used. |

Note that explicit enum mappings (`MapEnumValue`) and fallback values (`FallbackValue` in `MapEnum`)
are not affected by naming strategies.

<Tabs>
    <TabItem value="global" label="Global (mapper level)" default>

        Applied to all enums mapped inside this mapper.

        ```csharp
        // highlight-start
        [Mapper(EnumNamingStrategy = EnumNamingStrategy.SnakeCase)]
        // highlight-end
        public partial class CarMapper
        {
            ...
        }
        ```

    </TabItem>
    <TabItem value="enum" label="Enum (mapping method level)">

        Applied to the specific enum mapped by this method.
        Attribute is only valid on mapping method with enums as parameters.

        ```csharp
        [Mapper]
        public partial class CarMapper
        {
            // highlight-start
            [MapEnum(EnumMappingStrategy.ByName, NamingStrategy = EnumNamingStrategy.SnakeCase)]
            // highlight-end
            public partial CarMakeDto MapMake(CarMake make);
        }
        ```

    </TabItem>

</Tabs>

## Manually mapped enum values

To explicitly map enum values the `MapEnumValueAttribute` can be used.
Attribute is only valid on enum-to-enum, enum-to-string and string-to-enum mappings.

Explicit enum mappings are not affected by enum naming strategies.

```csharp
[Mapper]
public partial class CarMapper
{
    [MapEnum(EnumMappingStrategy.ByName)]
    // highlight-start
    [MapEnumValue(CarFeature.AWD, CarFeatureDto.AllWheelDrive)]
    // highlight-end
    public partial CarFeatureDto MapFeature(CarFeature feature);

    // highlight-start
    [MapEnumValue("AWD", CarFeatureDto.AllWheelDrive)]
    // highlight-end
    public partial CarFeatureDto MapFeatureFromString(string feature);

    // highlight-start
    [MapEnumValue(CarFeatureDto.AllWheelDrive, "AWD")]
    // highlight-end
    public partial string MapFeatureToString(CarFeatureDto feature);
}
```

## Ignore enum values

To ignore an enum value the `MapperIgnoreSourceValue` or `MapperIgnoreTargetValue` attributes can be used.
This is especially useful when applying [strict enum mappings](#strict-enum-mappings).

```csharp
[Mapper]
public partial class FruitMapper
{
    // highlight-start
    [MapperIgnoreSourceValue(Fruit.Apple)]
    [MapperIgnoreTargetValue(FruitDto.Pineapple)]
    // highlight-end
    public partial FruitDto Map(Fruit source);
}
```

## Fallback value

To map to a fallback value instead of throwing when encountering an unknown value,
the `FallbackValue` property on the `MapEnum` attribute can be used.

`FallbackValue` is supported by `ByName` and `ByValueCheckDefined`.
`FallbackValue` is not affected by enum naming strategies.

```csharp
[Mapper]
public partial class CarMapper
{
    // highlight-start
    [MapEnum(EnumMappingStrategy.ByName, FallbackValue = CarFeatureDto.Unknown)]
    // highlight-end
    public partial CarFeatureDto MapFeature(CarFeature feature);
}
```

## One side strict enum member mappings

By default Mapperly emits diagnostics with a severity of warning if there are unmapped source or target enum members.
To enforce strict enum member mappings on only either the source or the target,
the `RequiredEnumMappingStrategy` can be used. By default this property will inherit the value from `RequiredMappingStrategy`.

<Tabs>
    <TabItem value="global" label="Global (mapper level)" default>
    
        Sets the `RequiredEnumMappingStrategy` for all methods within the mapper,
        by default it is `Both` requiring all members to be mapped.
        This can be overridden by individual mapping methods using `MapperRequiredMappingAttribute`.
    
        ```csharp
        // highlight-start
        [Mapper(RequiredEnumMappingStrategy = RequiredMappingStrategy.Source)]
        // highlight-end
        public partial class CarMapper
        {
            ...
        }
        ```
    
    </TabItem>
    <TabItem value="local" label="Local (mapping method level)">
    
        Applied to the specific mapping method.
    
        ```csharp
        [Mapper]
        public partial class CarMapper
        {
            // highlight-start
            [MapperRequiredMapping(RequiredMappingStrategy.Source)]
            // highlight-end
            public partial CarFeatureDto MapCar(CarFeature feature);
        }
        ```
    
    </TabItem>
</Tabs>
